Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 003 / db_dbug2.arc / READ.ME < prev

Wrap

Text File | 1987-03-11 | 15.6 KB | 396 lines

dBASE III Debugging Utilities By Curtis H. Hoffmann Ver 2.0 03-10-87 There are currently eight utilities on this disk, with source code, designed for helping to debug and speed up any dBASE III or III Plus .PRG files. These utilities are: DB_BRUTE.COM: Displays the .DBF file structure and .NDX index key for every .DBF and .NDX file in the current subdirectory. If INSERT.COM has been used, then DB_BRUTE can link the .NDX files to the associated .DBF files. DB_FILES.COM: Follows the tree structure of your .PRG files and links your .NDX files to the associated .DBF files, then prints out the header data for both types of files. DB_STRCT.COM: Displays the tree structure of your files, every variable used or called out in each file, and flags any loop mismatches (ie - missing ENDIF statements, or too many ENDDO's) DB_VARIBS.COM: Shows the variables as they are declared or first invoked from each file. Also lists each variable still active after returning from a nested file, and then shows all of the variables that have not been RELEASED as well as those that have not been used. DB_COMP.COM: Strips out all leading spaces, blank lines and comments. Removes all unnecessary spaces and reduces all commands and functions to their four character minimum. This utility also expands a condensed file, adding indents for each DO/IF loop, but all comments from the original file will be lost. LISTING.COM: Allows you to print out date/time stamped listings of your programs, either one at a time, or in batch mode and automate the process. INSERT.COM: Takes a particular .NDX file, goes to a section of wasted space in the header, and inserts the name of the associated .DBF file where it can be easily found, but will not affect the operation of the file. PICKIT.COM: The complement of INSERT.COM. Equivalent to DB_BRUTE, but one .NDX file at a time and displays only to screen. To run either of these programs, just type the name of the desired utility and hit ENTER. DB_STRCT, DB_FILES and DB_VARIB will ask for the starting .PRG filename, the filename you want the output stored to, and whether you want to check all of the files in a dBASE tree, or just one file. (See below for DB_FILES.) DB_COMP will ask for the starting filename, if you want to work on all of the files in a tree or just one, and if you want to compress or expand those files. DB_BRUTE and DB_FILES output to printer only. INSERT and PICKIT take their parameters from the command line. for more detail, just type the program name and hit [ENTER]. LISTING can take a filename as a parameter on the command line (ie LISTING PRINT.ME). If it is not given a parameter, it will automatically look for a file named LISTING.DAT in the current subdirectory. If not found, it will tell you more about itself. LISTING.DAT should just be a collection of filenames (with extensions) in the order you want them printed out, one filename per line. ================================================================ There should also be three supplementary text files in this .ARC: READ.ME: This file. The master instruction doc. INSERT.PRG: A dBASE III file that demonstrates the use of INSERT.COM to tag a .NDX file when it is first created. Syntax: DO INSERT WITH "dbf_name", "ndx_name", "ndx_key" DB3_HDR.DOC: An explanation of the .DBF and .NDX header contents and descriptions. Can be used with any language, not just Turbo Pascal. Good for creating your own routines, or helping to understand mine. ================================================================ The operation of these utilities is very simple. What they do, and what the output represents, is a little more complex. DB_COMP, DB_FILES, DB_STRCT, and DB_VARIB assume a .PRG extension on the files they will be working on. DB_COMP automatically feeds its output to a file with the same name as the one it is operating on, and appends a .NEW extension to it. =============================================================== Theory of operation (this is just a theory, mind you): In any given set of dBASE program files, you can employ a series of IF/ENDIF, DO CASE/ENDCASE, and DO WHILE/ENDDO loops, as well as make calls to other .PRG files with a DO <filename> command. The results of the DO <filename> call gives a tree structure to the overall program file set. Some of these utilities explore that tree structure as they perform their various operations. However, if you only want to compress, or debug, just one file then the search of the tree structure is skipped and the selected operations occur normally. Note: The output has to go somewhere, so you may be asked for an output filename. If you want the output sent directly to a printer, choose PRN; to output to screen, type CON. ========= DB_STRCT: The first part of the report shows the tree structure and all of the various files as they are invoked in turn. Note, if you call a particular file several times in your program, that filename will appear that many times, and in the location of the tree that you invoked it. Also, if a .PRG file is called with a DO statement but can not be found (ie -- doesn't exist or is a typo) then an ALERT message will state the filename and the file that tried to call it, then continue with the rest of the report. The second part of the report shows the variables used or called out in each file, printing the files only once each. At the same time, the utility is checking for loop mismatches, too many END statements, or missing END statements at the end of each file. A caution statement is printed out as each condition is encountered. example of what could be done wrong in a program: IF A=B DO CASE CASE F=1 CASE F=2 ENDIF <-- Expecting ENDCASE, found ENDIF ENDDO <-- Expecting ENDIF, found ENDDO ENDIF ENDIF <-- Too many ENDIF statements ========= DB_VARIB: The first part of this report shows each variable as it is encountered for the first time, either as a PUBLIC declaration, or a straight statement and treated as a local variable. Either way, these variables are attached to the filename it is first encountered in, and then printed out as invoked by that file. Then, as the end of each file is encountered, the variables released from that file are printed out, as well as a list of variables still active. Also, if a variable has been released, the next time it is invoked it will be treated as a new variable and printed out as such. Like DB_STRCT, DB_VARIB will report a .PRG file that is called but can not be found, and continue with the rest of the report. The second part of the report is two lists. The first list shows all of the variables that were invoked but never used -- just a waste of memory space. The second list shows the variables declared PUBLIC and never RELEASEd. These variables may create conflicts in other dBASE programs or when the same program is run again. ========= DB_COMP: This utility is intended to speed up the operation of your dBASE programs, as well as make them more readable if you lose your original source listing, or never had one to begin with. In compression mode, DB_COMP strips out all unnecessary spaces, comments, and blank lines. It also reduces the command and function words to their four-character minimum length. In expansion mode, the command and function words are expanded to their full length, and the lines are indented to give a pretty-print appearance. NOTE: Ashton-Tate says that compressing your files this way will give you a significantly faster program. Yes and No. What happens: When dBASE first reads a file to execute, it has to wade through the spaces and comments to find the actual executable code and then read the extra characters in the reserved words to find the next operation or operator. In this way, compressing the files will reduce the time that dBASE wastes in interpreting what you wrote. HOWEVER: dBASE only needs to do this once when it first encounters a file. Afterwards, the file is converted into machine code and is now completely optimized. Because of this, you will not see any time savings on highly repetitive loops that don't call any other files. example: Is no faster than DO WHILE A<=1000 DO WHIL A<=1000 A=A+1 A=A+1 ? 'I am Wasting Time' ? 'I am Wasting Time' ENDDO ENDD So, if you are doing lots of calculations on a datafile, you will save more time by the creative use of INDEX and SET RELATION than you will by compressing all your files. BUT, you will see a significant speed-up in your user interfaces and menu screens by compressing those parts of your program. === LISTING: This has been explained above. However, if LISTING.DAT is found, then LISTING will print out every file it is told to, sequentially, and with form feeds between listings. At the top of each listing, it will date and time stamp the output, and include the subdirectory it's in. I did this for the obvious reasons. If it's not obvious to you, drop me a note and I'll explain further. === INSERT: Look the DB3_HDR.DOC, under the section on .NDX files. You'll see that the space from byte 280 to 511 is completely wasted. dBASE does not use it at all. And, because Ashton-Tate stupidly did not give us a way to tell what .DBF file was in use when a .NDX was created, I wrote this utility. It takes the .DBF name you give it and sticks it starting at location 495. The name will remain untouched, and will not affect your data, until you recreate the index. === PICKIT: This utility just looks at 16 bytes starting with location 495 in a given .NDX and displays what it finds. If the associated .DBF file is not in the same subdirectory, it will suggest that this index has not yet been tagged. ================================================================ Tricks and Suggestions: Rather than just operate on one file at a time, use the All option from the utility menu screens. These utilities can process 20 large dBASE program files in less than 5 minutes on a PC XT, with hard disk. On an AT, the time drops down to 1.5 minutes. If you want to operate on a segment of a dBASE tree, rather than the entire tree, just type in the name of the file you want to start with, and choose all. The utilities aren't smart enough to work backwards up a tree structure if they haven't started from the top. example: Partial output of DB_STRCT DEFECT-- MENU1--- IN_MENU- INP_1--- UP_INP_1 UNASSIGN GEN_MENU CALC_1-- CALC_2-- OUT_1 OUT_2 OUT_3 CALC_3-- OUT_1 PROG_LST So, if you just wanted to analyze the input portion of the tree, you'd start with IN_MENU: Partial output of DB_STRCT IN_MENU- INP_1--- UP_INP_1 UNASSIGN When you do an index from now on, use something like INSERT.PRG instead of a straight index command. This way, troubleshooting or modifying your programs at a later date will be made easier because you'll know what .DBF file each .NDX is for. BACKUP ALL OF YOUR FILES BEFORE DOING ANYTHING UNUSUAL TO THEM. This is just common sense. I'm not saying that these utilities will munch your hard disk or floppies, but it's stupid to take chances on any form of new software, commercial or public domain. NOTE: These utilities were written and compiled in Turbo Pascal ver. 3.0. Now, not every PC compatible is 100% compatible with the IBM PC (The Zenith Z-100 chokes on Turbo ver 3.0 itself, as well as any programs compiled on it). So, if your machine can not run these utilities, just get a copy of Turbo ver 2.0, config it for your PC, and recompile the utilities. I tried to make them as generic as possible, so only the GETDIR(0,PATH) command may give you any problems. If it does, just remove it. ================================================================= Statements of stuff. I'm putting these utilities, and the source code, into the public domain, with the following restrictions: 1) You may make as many copies of these utilities as you want, and give them to anyone you want. Just keep this READ.ME file together with the rest of the files. Among other things, this is the documentation and makes life easier for anyone trying to use these utilities. 2) You don't remove my name from any of the files. I'm vain, I admit it, and I want to get as much recognition for this work as I can squeeze out of it. (By the way, have you read my book? Just look under Hoffmann in the science fiction section of your local bookstore. It came out in Feb.; the title is _Project: Millennium_.) ========== Revision History: 1.0 10-28-86 - Initial release. Included DB_STRCT, DB_VARIB, DB_COMP. 2.0 03-10-87 - Added error checking to DB_STRCT and DB_VARIB to alert user that .PRG file is missing from subdirectory. - Included INSERT, PICKIT, LISTING, DB_FILES, DB_BRUTE, and DB3_HDR.DOC to the archive. ========= I believe in the shareware concept, so if you really like what I've done here, any amount would be appreciated, but I think $10 is reasonable. However, I really do want to hear from you. If you have any comments, suggestions for future improvements, complaints, or bug reports, please write to me and let me know. Also, if you come across someone else that's also written utilities like these, let me know. If they've done better than I have I'd rather use what they've written and be able to sit back and be lazy. If you make any improvements or changes to the source, let me know. This way, the best of all changes will be incorporated in the next release. Further, if you write and tell me what you think of these utilities, I'll put you on a mailing list and alert you to any improvements I make or someone else suggests. Write to me: Curtis H. Hoffmann NCR Comten QE Dept. 2700 Snelling Ave. N. St. Paul, Mn. 55113 Either way, thanks for looking these files over. 'dios.